---
title: Operational runbook
summary: Deployment, verification, status codes, logging and troubleshooting guidance for DBConnectionAPI.
status: draft
owner: Architecture
last_reviewed: 2026-10-09
---

# Operational runbook

## Deployment

| Item | Finding |
| --- | --- |
| Hosting | IIS in-process, .NET 10 |
| Build and deploy | Azure DevOps pipelines; v2 uses `AppType` `coreapi`, v3 uses `appType: api` with the standard deploy template |
| Application pool | v2: No Managed Code, Integrated pipeline; v3: on-demand start mode |
| Pipeline SDK | 8.x and 9.x configured against a `net10.0` target; see [Tech debt](tech-debt.md#td-01-pipeline-sdk-version-does-not-match-net10.0) |

Pipeline details are on [Hosting pipeline](hosting-pipeline.md).

## Environments

Base addresses and Environment API tracks are not determined from source**. Per-environment values are listed as unknown on [Configuration](configuration.md#environment-variance).

## Health verification

No health-check endpoint is mapped. To verify a deployment:

1. Open the Swagger UI at `swagger` and confirm the document at `swagger/v1/swagger.json` loads
2. Call one retrieval endpoint with a known instance and user and confirm status 200 ([Endpoints](endpoints.md))

Swagger is active in every environment ([Tech debt](tech-debt.md#sec-05-swagger-exposed-in-every-environment)).

## Status codes

| Status | Meaning | Rule |
| --- | --- | --- |
| 200 | Success; also returned by Admin operations with an `Error` entry | [BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200) |
| 400 | Oracle TNS alias not resolved | [BR-DBC-015](business-rules.md#br-dbc-015-tns-alias-errors-map-to-400) |
| 404 | Secure setting not found | [BR-DBC-009](business-rules.md#br-dbc-009-missing-secure-setting-returns-404) |
| 500 | Probe failure after retries and other manager failures | [BR-DBC-016](business-rules.md#br-dbc-016-other-final-failures-map-to-500) |
| 401 / 403 | Authorization failure; status not visible in source** | [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) |
| Unhandled exceptions | Status not visible in source** | [BR-DBC-010](business-rules.md#br-dbc-010-credential-split-at-the-first-pipe%2C-unguarded) |

## Logs

| Item | Finding |
| --- | --- |
| Logger | `ISaifLogService` (audit, validation and per-attempt error entries) |
| Sink | Not determined from source** |
| Admin operations | No log entry is written |
| Telemetry | OpenTelemetry, owner `Architecture` |

## Environment configuration

Key names and the resolution chain are on [Configuration](configuration.md). Provision the three templates and the secure credential keys in the Environment API group `dbconnectionapi` before first use.

## Error scenarios

| Symptom | Likely cause | Action |
| --- | --- | --- |
| 404 on a retrieval call | Secure credential key missing for that instance and user | Create the key following the pattern on [Configuration](configuration.md#environment-api-settings) |
| 400 on an Oracle call | TNS alias not resolved | Verify the alias on the host |
| 500 on a retrieval call | Probe failed on all four attempts: invalid credentials, database unavailable or network interruption | Check the database and the stored credential |
| Stale connection string after credential rotation | Cache never expires | Restart the application ([BR-DBC-004](business-rules.md#br-dbc-004-cache-entries-never-expire)) |
| Admin call returns 200 with an `Error` entry | Credential value has no pipe separator | Correct the secure value ([BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200)) |
| Pipeline fails on the CI definition | Project file reference does not exist | See [Tech debt](tech-debt.md#td-02-ci-pipeline-project-file-points-at-a-missing-project) |

## Monitoring and alerting

No alerts, dashboards or health probes are defined in the repository**. Error entries from failed probe attempts are the main signal*.

## Related documentation
- [API index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Hosting pipeline](hosting-pipeline.md)
- [Endpoints](endpoints.md)
- [Authentication and authorization](authentication-authorization.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Data model](data-model.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure,
> naming conventions, or contextual evidence where direct confirmation was not
> available in source artifacts. Statements marked with `**` could not be
> confirmed; treat as unknown until verified.

## Sources
- DBConnectionAPI/DBConnectionAPI/Startup.cs
- DBConnectionAPI/DBConnectionAPI/Services/ConnectionManager.cs
- DBConnectionAPI/DBConnectionAPI/Controllers/AdminController.cs
- DBConnectionAPI/DBConnectionAPI/web.config
- .azdo/DBConnectionAPI/azure-pipelines.yml
- .azdo/DBConnectionAPI/variables/vars.yml
- azure-pipelines.yml